<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta name="description" content="API docs for the debugFillProperties method from the SpriteWidget class, for the Dart programming language.">
  <title>debugFillProperties method - SpriteWidget class - spritewidget library - Dart API</title>
  <!-- required because all the links are pseudo-absolute -->
  <base href="../..">

  <link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500,400i,400,300|Source+Sans+Pro:400,300,700" rel="stylesheet">
  <link rel="stylesheet" href="static-assets/github.css">
  <link rel="stylesheet" href="static-assets/styles.css">
  <link rel="icon" href="static-assets/favicon.png">

</head>

<body>

<div id="overlay-under-drawer"></div>

<header id="title">
  <button id="sidenav-left-toggle" type="button">&nbsp;</button>
  <ol class="breadcrumbs gt-separated dark hidden-xs">
    <li><a href="index.html">spritewidget</a></li>
    <li><a href="spritewidget/spritewidget-library.html">spritewidget</a></li>
    <li><a href="spritewidget/SpriteWidget-class.html">SpriteWidget</a></li>
    <li class="self-crumb">debugFillProperties method</li>
  </ol>
  <div class="self-name">debugFillProperties</div>
  <form class="search navbar-right" role="search">
    <input type="text" id="search-box" autocomplete="off" disabled class="form-control typeahead" placeholder="Loading search...">
  </form>
</header>

<main>

  <div class="col-xs-6 col-sm-3 col-md-2 sidebar sidebar-offcanvas-left">
    <h5>SpriteWidget class</h5>
    <ol>
      <li class="section-title"><a href="spritewidget/SpriteWidget-class.html#constructors">Constructors</a></li>
      <li><a href="spritewidget/SpriteWidget/SpriteWidget.html">SpriteWidget</a></li>
    
      <li class="section-title">
        <a href="spritewidget/SpriteWidget-class.html#instance-properties">Properties</a>
      </li>
      <li><a href="spritewidget/SpriteWidget/rootNode.html">rootNode</a></li>
      <li><a href="spritewidget/SpriteWidget/transformMode.html">transformMode</a></li>
      <li class="inherited"><a href="spritewidget/SpriteWidget/child.html">child</a></li>
      <li class="inherited"><a href="dart-core/Object/hashCode.html">hashCode</a></li>
      <li class="inherited"><a href="spritewidget/SpriteWidget/key.html">key</a></li>
      <li class="inherited"><a href="dart-core/Object/runtimeType.html">runtimeType</a></li>
    
      <li class="section-title"><a href="spritewidget/SpriteWidget-class.html#instance-methods">Methods</a></li>
      <li><a href="spritewidget/SpriteWidget/createRenderObject.html">createRenderObject</a></li>
      <li><a href="spritewidget/SpriteWidget/updateRenderObject.html">updateRenderObject</a></li>
      <li class="inherited"><a href="spritewidget/SpriteWidget/createElement.html">createElement</a></li>
      <li class="inherited"><a href="spritewidget/SpriteWidget/debugDescribeChildren.html">debugDescribeChildren</a></li>
      <li class="inherited"><a href="spritewidget/SpriteWidget/debugFillProperties.html">debugFillProperties</a></li>
      <li class="inherited"><a href="spritewidget/SpriteWidget/didUnmountRenderObject.html">didUnmountRenderObject</a></li>
      <li class="inherited"><a href="dart-core/Object/noSuchMethod.html">noSuchMethod</a></li>
      <li class="inherited"><a href="spritewidget/SpriteWidget/toDiagnosticsNode.html">toDiagnosticsNode</a></li>
      <li class="inherited"><a href="spritewidget/SpriteWidget/toString.html">toString</a></li>
      <li class="inherited"><a href="spritewidget/SpriteWidget/toStringDeep.html">toStringDeep</a></li>
      <li class="inherited"><a href="spritewidget/SpriteWidget/toStringShallow.html">toStringShallow</a></li>
      <li class="inherited"><a href="spritewidget/SpriteWidget/toStringShort.html">toStringShort</a></li>
    
      <li class="section-title inherited"><a href="spritewidget/SpriteWidget-class.html#operators">Operators</a></li>
      <li class="inherited"><a href="dart-core/Object/operator_equals.html">operator ==</a></li>
    
    
    
    </ol>
  </div><!--/.sidebar-offcanvas-->

  <div class="col-xs-12 col-sm-9 col-md-8 main-content">
    <h1>debugFillProperties method</h1>

    <section class="multi-line-signature">
      <div>
        <ol class="annotation-list">
          <li>@override</li>
        </ol>
      </div>
      <span class="returntype">void</span>
      <span class="name ">debugFillProperties</span>
(<wbr><span class="parameter" id="debugFillProperties-param-properties"><span class="type-annotation">DiagnosticPropertiesBuilder</span> <span class="parameter-name">properties</span></span>)
    </section>
    <section class="desc markdown">
      <p>Add additional properties associated with the node.</p>
<p>Use the most specific <code>DiagnosticsProperty</code> existing subclass to describe
each property instead of the <code>DiagnosticsProperty</code> base class. There are
only a small number of <code>DiagnosticsProperty</code> subclasses each covering a
common use case. Consider what values a property is relevant for users
debugging as users debugging large trees are overloaded with information.
Common named parameters in <code>DiagnosticsNode</code> subclasses help filter when
and how properties are displayed.</p>
<p><code>defaultValue</code>, <code>showName</code>, <code>showSeparator</code>, and <code>level</code> keep string
representations of diagnostics terse and hide properties when they are not
very useful.</p><ul><li>Use <code>defaultValue</code> any time the default value of a property is
uninteresting. For example, specify a default value of null any time
a property being null does not indicate an error.</li><li>Avoid specifying the <code>level</code> parameter unless the result you want
cannot be be achieved by using the <code>defaultValue</code> parameter or using
the <code>ObjectFlagProperty</code> class to conditionally display the property
as a flag.</li><li>Specify <code>showName</code> and <code>showSeparator</code> in rare cases where the string
output would look clumsy if they were not set.
<pre class="language-dart"><code class="language-dart">new DiagnosticsProperty&lt;Object&gt;('child(3, 4)', null, ifNull: 'is null', showSeparator: false).toString()
</code></pre>Shows using <code>showSeparator</code> to get output <code>child(3, 4) is null</code> which
is more polished than <code>child(3, 4): is null</code>.
<pre class="language-dart"><code class="language-dart">new DiagnosticsProperty&lt;IconData&gt;('icon', icon, ifNull: '&lt;empty&gt;', showName: false)).toString()
</code></pre>Shows using <code>showName</code> to omit the property name as in this context the
property name does not add useful information.</li></ul>
<p><code>ifNull</code>, <code>ifEmpty</code>, <code>unit</code>, and <code>tooltip</code> make property
descriptions clearer. The examples in the code sample below illustrate
good uses of all of these parameters.</p>
<h2>DiagnosticsProperty subclasses for primitive types</h2><ul><li><code>StringProperty</code>, which supports automatically enclosing a <a href="dart-core/String-class.html">String</a>
value in quotes.</li><li><code>DoubleProperty</code>, which supports specifying a unit of measurement for
a <a href="dart-core/double-class.html">double</a> value.</li><li><code>PercentProperty</code>, which clamps a <a href="dart-core/double-class.html">double</a> to between 0 and 1 and
formats it as a percentage.</li><li><code>IntProperty</code>, which supports specifying a unit of measurement for an
<a href="dart-core/int-class.html">int</a> value.</li><li><code>FlagProperty</code>, which formats a <a href="dart-core/bool-class.html">bool</a> value as one or more flags.
Depending on the use case it is better to format a bool as
<code>DiagnosticsProperty&lt;bool&gt;</code> instead of using <code>FlagProperty</code> as the
output is more verbose but unambiguous.</li></ul>
<h2>Other important <code>DiagnosticsProperty</code> variants</h2><ul><li><code>EnumProperty</code>, which provides terse descriptions of enum values
working around limitations of the <code>toString</code> implementation for Dart
enum types.</li><li><code>IterableProperty</code>, which handles iterable values with display
customizable depending on the <code>DiagnosticsTreeStyle</code> used.</li><li><code>ObjectFlagProperty</code>, which provides terse descriptions of whether a
property value is present or not. For example, whether an <code>onClick</code>
callback is specified or an animation is in progress.</li></ul>
<p>If none of these subclasses apply, use the <code>DiagnosticsProperty</code>
constructor or in rare cases create your own <code>DiagnosticsProperty</code>
subclass as in the case for <code>TransformProperty</code> which handles <code>Matrix4</code>
that represent transforms. Generally any property value with a good
<code>toString</code> method implementation works fine using <code>DiagnosticsProperty</code>
directly.</p>
<h2>Sample code</h2>
<p>This example shows best practices for implementing <a href="spritewidget/SpriteWidget/debugFillProperties.html">debugFillProperties</a>
illustrating use of all common <code>DiagnosticsProperty</code> subclasses and all
common <code>DiagnosticsProperty</code> parameters.</p>
<pre class="language-dart"><code class="language-dart">class ExampleObject extends ExampleSuperclass {

  // ...various members and properties...

  @override
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    // Always add properties from the base class first.
    super.debugFillProperties(properties);

    // Omit the property name 'message' when displaying this String property
    // as it would just add visual noise.
    properties.add(new StringProperty('message', message, showName: false));

    properties.add(new DoubleProperty('stepWidth', stepWidth));

    // A scale of 1.0 does nothing so should be hidden.
    properties.add(new DoubleProperty('scale', scale, defaultValue: 1.0));

    // If the hitTestExtent matches the paintExtent, it is just set to its
    // default value so is not relevant.
    properties.add(new DoubleProperty('hitTestExtent', hitTestExtent, defaultValue: paintExtent));

    // maxWidth of double.infinity indicates the width is unconstrained and
    // so maxWidth has no impact.,
    properties.add(new DoubleProperty('maxWidth', maxWidth, defaultValue: double.infinity));

    // Progress is a value between 0 and 1 or null. Showing it as a
    // percentage makes the meaning clear enough that the name can be
    // hidden.
    properties.add(new PercentProperty(
      'progress',
      progress,
      showName: false,
      ifNull: '&lt;indeterminate&gt;',
    ));

    // Most text fields have maxLines set to 1.
    properties.add(new IntProperty('maxLines', maxLines, defaultValue: 1));

    // Specify the unit as otherwise it would be unclear that time is in
    // milliseconds.
    properties.add(new IntProperty('duration', duration.inMilliseconds, unit: 'ms'));

    // Tooltip is used instead of unit for this case as a unit should be a
    // terse description appropriate to display directly after a number
    // without a space.
    properties.add(new DoubleProperty(
      'device pixel ratio',
      ui.window.devicePixelRatio,
      tooltip: 'physical pixels per logical pixel',
    ));

    // Displaying the depth value would be distracting. Instead only display
    // if the depth value is missing.
    properties.add(new ObjectFlagProperty&lt;int&gt;('depth', depth, ifNull: 'no depth'));

    // bool flag that is only shown when the value is true.
    properties.add(new FlagProperty('using primary controller', value: primary));

    properties.add(new FlagProperty(
      'isCurrent',
      value: isCurrent,
      ifTrue: 'active',
      ifFalse: 'inactive',
      showName: false,
    ));

    properties.add(new DiagnosticsProperty&lt;bool&gt;('keepAlive', keepAlive));

    // FlagProperty could have also been used in this case.
    // This option results in the text "obscureText: true" instead
    // of "obscureText" which is a bit more verbose but a bit clearer.
    properties.add(new DiagnosticsProperty&lt;bool&gt;('obscureText', obscureText, defaultValue: false));

    properties.add(new EnumProperty&lt;TextAlign&gt;('textAlign', textAlign, defaultValue: null));
    properties.add(new EnumProperty&lt;ImageRepeat&gt;('repeat', repeat, defaultValue: ImageRepeat.noRepeat));

    // Warn users when the widget is missing but do not show the value.
    properties.add(new ObjectFlagProperty&lt;Widget&gt;('widget', widget, ifNull: 'no widget'));

    properties.add(new IterableProperty&lt;BoxShadow&gt;(
      'boxShadow',
      boxShadow,
      defaultValue: null,
      style: style,
    ));

    // Getting the value of size throws an exception unless hasSize is true.
    properties.add(new DiagnosticsProperty&lt;Size&gt;.lazy(
      'size',
      () =&gt; size,
      description: '${ hasSize ? size : "MISSING" }',
    ));

    // If the `toString` method for the property value does not provide a
    // good terse description, write a DiagnosticsProperty subclass as in
    // the case of TransformProperty which displays a nice debugging view
    // of a Matrix4 that represents a transform.
    properties.add(new TransformProperty('transform', transform));

    // If the value class has a good `toString` method, use
    // DiagnosticsProperty&lt;YourValueType&gt;. Specifying the value type ensures
    // that debugging tools always know the type of the field and so can
    // provide the right UI affordances. For example, in this case even
    // if color is null, a debugging tool still knows the value is a Color
    // and can display relevant color related UI.
    properties.add(new DiagnosticsProperty&lt;Color&gt;('color', color));

    // Use a custom description to generate a more terse summary than the
    // `toString` method on the map class.
    properties.add(new DiagnosticsProperty&lt;Map&lt;Listenable, VoidCallback&gt;&gt;(
      'handles',
      handles,
      description: handles != null ?
      '${handles.length} active client${ handles.length == 1 ? "" : "s" }' :
      null,
      ifNull: 'no notifications ever received',
      showName: false,
    ));
  }
}
</code></pre>
<p>Used by <a href="spritewidget/SpriteWidget/toDiagnosticsNode.html">toDiagnosticsNode</a> and <a href="spritewidget/SpriteWidget/toString.html">toString</a>.</p>
    </section>
    
    <section class="summary source-code" id="source">
      <h2><span>Implementation</span> </h2>
      <pre class="language-dart"><code class="language-dart">@override
void debugFillProperties(DiagnosticPropertiesBuilder properties) {
  super.debugFillProperties(properties);
  properties.defaultDiagnosticsTreeStyle = DiagnosticsTreeStyle.dense;
}</code></pre>
    </section>

  </div> <!-- /.main-content -->

  <div class="col-xs-6 col-sm-6 col-md-2 sidebar sidebar-offcanvas-right">
  </div><!--/.sidebar-offcanvas-->

</main>

<footer>
  <span class="no-break">
    spritewidget 0.9.16
  </span>

</footer>

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
<script src="static-assets/typeahead.bundle.min.js"></script>
<script src="static-assets/highlight.pack.js"></script>
<script src="static-assets/URI.js"></script>
<script src="static-assets/script.js"></script>


</body>

</html>
